simple_api.h File Reference

public methods for simple_api.c More...

#include "application_configuration.h"

Functions
void	sapiRegisterApplication (struct applicationConfiguration ac)
void	sapiRegisterGenericApplication ()
void	sapiStartApplication ()
void	setJoiningPermissions (unsigned int destination, unsigned char timeout)
void	sendData (unsigned int destinationShortAddress, unsigned int clusterId, unsigned char *data, unsigned char dataLength)

---

Detailed Description

public methods for simple_api.c

Rev

547

Author

dsmith

Date

2010-05-27 17:11:30 -0700 (Thu, 27 May 2010)

YOU ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.

---

Function Documentation

void sapiRegisterApplication

(

struct applicationConfiguration

ac

)

Configures the ZNP for our application. Sets which endpoint, profileId, etc. we're using as well as binding information.

Note:

Simple API can only register one application.

Parameters:

the

applicationConfiguration to register.

Precondition:

ZNP was initialized and ZCD_NV_LOGICAL_TYPE has been set (either COORDINATOR/ROUTER/END_DEVICE).

Postcondition:

can now use sapiStartApplication()

znpResult contains the error code, or ZNP_SUCCESS if success.

See also:

applicationConfiguration

void sapiRegisterGenericApplication

(

)

Configures the ZNP for a "generic" application: one endpoint, no binding or fancy stuff. Sets which endpoint, profileId, etc. we're using as well as binding information

Postcondition:

znpResult contains the error code, or ZNP_SUCCESS if success.

See also:

sapiRegisterApplication()

void sapiStartApplication

(

)

Starts the Zigbee stack in the ZNP using the settings from a previous sapiRegisterApplication(). After this start request process completes, the device is ready to send, receive, and route network traffic.

Note:

On a coordinator in a trivial test setup, it takes approximately 300mSec between START_REQUEST and receiving START_REQUEST_SRSP and then another 200-1000mSec from when we receive START_REQUEST_SRSP to when we receive START_CONFIRM.

Set START_CONFIRM_TIMEOUT based on size of your network.

Precondition:

sapiRegisterApplication() was a success.

Postcondition:

znpResult contains the error code, or ZNP_SUCCESS if success.

Note:

we will receive a START_CONFIRM if everything was ok. Should always receive a start confirm for a coordinator. Will only receive a start confirm on a router if we could join a zigbee network.

void sendData	(	unsigned int	destinationShortAddress,
		unsigned int	clusterId,
		unsigned char *	data,
		unsigned char	dataLength
	)

Sends a message to another device over the Zigbee network.

Note:

On a coordinator in a trivial test setup, it takes approximately 10mSec from sending ZB_SEND_DATA_REQUEST to when we receive ZB_SEND_DATA_CONFIRM.

handle is an optional user-definable reference number to match SEND_DATA_CONFIRM messages with the SEND_DATA_REQUEST message. This can be used to determine which SEND_DATA_REQUEST generated an error.

The ZNP will automatically require an ACK from the next device on the route when sending data. To require an ACK from the final destination, change MAC_ACK to APS_ACK. The downside is that this increases network traffic.

The radius is the maximum number of hops that this packet can travel through before it will be dropped. Should be set to the maximum number of hops expected in the network.

adjust SEND_DATA_CONFIRM_INTERVAL_MS and SEND_DATA_CONFIRM_TIMEOUT_MS based on network size, number of hops, etc.

Parameters:

	destinationShortAddress	the short address of the destination, or ALL_DEVICES or ALL_ROUTERS_AND_COORDINATORS to broadcast the message.
	clusterId	which cluster this message is for. User definable. Zigbee supports up to 2^16 clusters. A cluster is typically a particular command, e.g. "turn on lights" or "get temperature". If using a predefined Zigbee Alliance Application Profile then this cluster will follow the Zigbee Cluster Library.
	data	is the data to send.
	dataLength	is how many bytes of data to send. Must be less than MAXIMUM_PAYLOAD_LENGTH.

Precondition:

sapiStartApplication() was a success, START_CONFIRM received without any errors.

there is another device on the network with short address of destinationShortAddress and that device has successfully started its application using sapiStartApplication().

Postcondition:

srsp will contain a ZB_SEND_DATA_REQUEST_SRSP. We will receive a ZB_SEND_DATA_REQUEST_SRSP regardless of whether the message was successfully sent or not.

we will receive a ZB_SEND_DATA_CONFIRM if the message was successfully sent.

znpResult contains the error code, or ZNP_SUCCESS if success.

void setJoiningPermissions	(	unsigned int	destination,
		unsigned char	timeout
	)

Sets the Joining Permissions for this device or other devices. By default, after a setStartupOptions(CLEAR_CONFIG), joining is set to allow all devices, indefinitely.

Parameters:

	destination	which short address to set joining permissions for, or ALL_ROUTERS_AND_COORDINATORS to set joining permissions for all.
	timeout	how long in seconds to allow permissions, or if set to NO_TIMEOUT then joining will be on indefinitely.

Postcondition:

znpResult contains the error code, or ZNP_SUCCESS if success.